spec: define the confirmation contract behind `action.ai.requiresConfirmation` by huangyiirene · Pull Request #16531 · objectstack-ai/objectstack

huangyiirene · 2026-09-07T07:35:09Z

Clause-②: yes

Executes decision batch #54 (maintainer 「同意」 on recommendation A). This is the spec half only — it defines the contract and registers the refusal code. The runtime enforcement in invokeBusinessAction is #15942, which remains open and is not addressed here.

Contract review at CONTRACT_REVIEW_TIER (claude-fable-5-1): PASS — no blocking findings (comment 5567317321). Six advisories were held for a repair pass; all six have landed and are itemised under The repair pass below. The load-bearing decision was re-confirmed by that review and is untouched: the refusal gates on the DECLARED action.ai.requiresConfirmation === true, never on actionLooksDestructive, and the runtime is not in this diff.

The four deliverables

1. The request-side contract — packages/spec/src/contracts/ai-service.ts, directly under AIToolDefinition:

AI_ACTION_CONFIRMATION_MEMBER = 'confirm' — one exported constant fixing the member's spelling, so the door that refuses and the client that retries read the same symbol instead of each hand-spelling it.
AIActionConfirmation — the closed boolean member, declared once and mixed into each door's request shape rather than restated by it.

It rides at the top level of the action request, and the contract now NAMES the two request shapes it is destined for rather than gesturing at them: the MCP run_action tool input (actionName / objectName / recordId / params, packages/mcp/src/mcp-http-tools.ts) and the runtime action door's own request object — the input argument of invokeBusinessAction (objectName / recordId / params, packages/runtime/src/action-execution.ts), which the MCP bridge builds that object from.

Two placements were considered and rejected, and the reasons are written into the contract:

Not inside params. That bag is CLOSED against the author's own declared input vocabulary: enforceActionParams (ADR-0104 D2, strict by default since 17.0) rejects any key that is neither a declared param nor a built-in, so on an action that declares params a platform confirm riding there is REFUSED as an unknown action param — a 400 raised before the confirmation gate is ever reached. On an action declaring no params that check is a pass-through, so the same member would be silently accepted instead: one placement, two opposite behaviours, which on its own disqualifies it for a safety member.
Not a transport header. Invisible to the tool schema an agent reads, so the model cannot discover the retry it is being told to make; a header exists only at an HTTP edge while the action door itself is a plain function handed a request object; and a free-form header is an OPEN channel, which is the one thing a safety member must not be.

2. The refusal — ACTION_CONFIRMATION_REQUIRED, registered in ERROR_CODE_LEDGER under @objectstack/runtime (the package that owns both action doors, beside its ACTION_DISABLED sibling), answered 428. error.details is ActionConfirmationRequiredDetails: the action name, its object, and the exact member to set, so an agent builds the retry mechanically instead of re-parsing the prose it was handed.

3. The two misleading passages — ai/tool.zod.ts's requiresConfirmation retirement guidance and the ADR-0049 semantic entry's replacement / acceptanceCriteria — rewritten so they no longer describe an approval queue, and (after the review) so they no longer assert enforcement that does not exist yet. See A4 below: the wording is contract-referential and says plainly that the flag stops nothing until the door lands.

4. Changeset minor on @objectstack/spec. Additive: three new exports, one new union member, zero removals — check:api-surface reports the surface unchanged apart from the additions.

Which predicate gates the refusal, and why

The DECLARED flag: action.ai.requiresConfirmation === true. Never actionLooksDestructive.

The MCP list_actions projection at packages/runtime/src/action-execution.ts:1014 reads

requiresConfirmation: actionLooksDestructive(deps, action),

and actionLooksDestructive (:979) returns the declared flag when the author set it and otherwise falls through to a destructiveness heuristic, per the #7828 Option A ruling. So the listing reports declared-flag-or-guess.

The ruling says "an action declaring ai.requiresConfirmation: true". Writing the refusal against actionLooksDestructive would make an action whose author declared nothing start refusing on a guess — well past what was ruled, and in the direction that breaks working callers.

The two are not the same predicate and the contract says so explicitly. They also answer different questions, so both are honoured without contradiction:

	listing field	refusal gate
asks	should a client ASK the human?	will the server REFUSE?
declared `true`	`true`	refuses without the member
declared `false`	`false`	never refuses
declared absent, heuristic hit	`true` (heuristic)	does not refuse

The member is accepted on every AI-facing action call and required only on the declared-gated ones. So a client that confirms whenever a listing says requiresConfirmation: true is always correct — over-confirming is free — while inferring "no door will ever refuse" from a listing's false is sound precisely because the listing's predicate is the wider of the two. list_actions is unchanged.

Why 428, and why a ledger code beside `PRECONDITION_REQUIRED`

The card rules 4xx: the request is valid but incomplete, and the caller can fix it. 428 is the platform's own reading of exactly that condition — packages/cli/src/utils/secret-reference-union.ts:189 already records it as "the standard catalog's 'request is missing a required precondition'". 409 was rejected: there is no state conflict, and the identical call with the member set succeeds against unchanged server state. 422 was rejected: the definition is fine.

The code is not a re-spelling of the standard member. PRECONDITION_REQUIRED says some precondition is missing, which leaves a caller unable to tell a confirmation gate from a missing conditional header and unable to build the retry; this code says which precondition, on which action — the same discrimination its *_DISABLED and FLOW_* neighbours make. Measured: standardSynonymOf('ACTION_CONFIRMATION_REQUIRED') returns undefined, with CONFLICT and FORBIDDEN lit as positive controls in the same run — now a standing pin rather than a one-off probe.

Registered ahead of its producer by design — the FLOW_INPUT_SCHEMA_INVALID split shape the ledger already sanctions — and the row cites the cards that make it a split rather than a residue (#16293 for this half, #15942 for the producer, decision batch #54 for the ruling that split them).

Deliberately not done here

No confirm member added to the live MCP run_action inputSchema (packages/mcp/src/mcp-http-tools.ts). Adding it before MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 enforces it would ship a member every LLM client can see and the runtime accepts and ignores — a safety flag that is merely accepted, which is precisely the defect tool.requiresConfirmation was retired for under ADR-0049. The spec declares the member; each door grows it in the same change that enforces it, so no window exists where it is accepted and ignored. The hand-off is recorded on MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 (comment 5567321513).
The runtime's own "HITL hint" comment, and ui/action.zod.ts's ai guidance, are untouched. The card assigns the first to MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942; the second sits under action-requires-confirmation-docblock.pin.test.ts.
content/docs/ai/actions-as-tools.mdx is accurate today and becomes incomplete only once the server refuses — MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942's job, already on the drift bot's list.

The repair pass — the six advisories held from the review

All measurements below were taken in a worktree pinned to merge-base a5eccf9257, at final head 10abca6c28.

A1 — a false precedent citation, corrected. The row cited UNIQUE_SCOPE_CONFIRMATION_REQUIRED as "registered beside the same standard member for the same reason". Measured: that gate answers 409 (packages/cloud-connection/src/marketplace-install-local-plugin.ts:829 closes }, 409); its own ledger row says 409; HttpStatusErrorCodeMap maps 409 to RESOURCE_CONFLICT and 428 to PRECONDITION_REQUIRED). It is therefore a sibling in KIND only — the platform's other confirmation gate that registers its own code — and no precedent for choosing 428 over 409. 428 itself is unchanged.
A3 — the producerless row now cites its cards. [#16293] heads the row in the sibling convention, and the producerless paragraph names MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 and decision batch Prepare v0.2.0 release for ObjectStack packages #54, with one sentence saying why the numbers are the point: a producerless row with no card behind it is the "registered but unemittable" retirement class, and this one is a split.
A4 — SECURITY: the prose is contract-referential until enforcement exists. The rewritten guidance and the migration entry asserted present-tense enforcement, and the new acceptanceCriteria told an author to "invoke it WITHOUT the confirmation member and observe the call refused" — an instruction that, before MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942, executes the destructive action. All three sites now describe what the contract DECLARES, say plainly that the door which performs the refusal has not landed, and explicitly warn against that verification: "until that door ships, such a call is not refused, it RUNS". The queue language is NOT restored — it stays deleted, exactly as the ruling requires. Nothing here relies on release ordering.
- The third site is the changeset body, corrected in the same pass. It is the release-time carrier of the identical claim, so leaving it present-tense would have published the louder version of it at the next cut — the failure mode A4 names. Its grade is unchanged (minor, additive).
- The tracker ids sit in a code comment beside the guidance table, not in the prescription string: check:doc-authoring reds on an internal issue id inside a customer-facing prescription (a hoisted guidance const is one of its recognised positions; ADR ids stay, #NNNN does not). The migration entry's replacement / acceptanceCriteria are not swept — measured against dozens of sibling semantic entries that carry #NNNN in those same two fields today, on a green tree — so both name MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 directly.
A5 — a factual error corrected, and the stronger reason added. "Flow call action nodes" is gone: FlowNodeAction (packages/spec/src/automation/flow.zod.ts:27) enumerates script / subflow / connector_action and no action-call node (control: subflow is present in the same enum). Added, as the decisive reason the contract was missing: params is strict by default, so an undeclared confirm there is REJECTED rather than merely colliding — with the asymmetry spelled out, since enforceActionParams is a pass-through for an action that declares no params.
A6 — the missing pin. Measured before: git grep -l over *.test.ts / *.spec.ts returned 0 files for each of AI_ACTION_CONFIRMATION_MEMBER, AIActionConfirmation, ActionConfirmationRequiredDetails and ACTION_CONFIRMATION_REQUIRED, while the same glob lights 26 files for ERROR_CODE_LEDGER and the same terms light non-test files. packages/spec/src/contracts/action-confirmation-contract.pin.test.ts now carries the feat(spec): register FLOW_INPUT_SCHEMA_INVALID — the never-dispatched ADR-0112 code for the definition-level input-schema refusal #12611 shape — an accepts case through ErrorCode.parse, the ledger row under @objectstack/runtime (plus a control that no other owner holds it), standardSynonymOf(...) undefined against two lit controls — and the compile witness: confirmationMember typed to typeof AI_ACTION_CONFIRMATION_MEMBER, with a near-miss spelling and a string confirm each behind a @ts-expect-error. Those two directives are LIT rather than decorative: an unused directive is TS2578, this file carries no entry in test-typecheck-debt.json, and check:test-typecheck is green — which is only possible if both are consumed.
A7 — the second enumeration site, removed rather than pinned. The contract docblock no longer spells out the heuristic's legs; it references actionLooksDestructive by name and says the signals are named once, beside the authorable key in ui/action.zod.ts. Why removal over extending the pin: the enumeration is a RUNTIME implementation detail, and ActionAiSchema.requiresConfirmation docblock still names confirmText as a destructive signal — the #7828 ruling removed that leg #13865's pin exists to hold ONE authoring surface against the classifier. Extending it to a second site would freeze the same list in two places and make both rot-prone; deleting the restatement leaves nothing to rot and keeps the pin's subject singular. The changeset keeps its one mention, deliberately: it is frozen into CHANGELOG.md at release as a record of the decision, not a live authoring surface.

Accepted as-is per the review's rulings: A8 (the acceptanceCriteria rewrite is in-spirit and kept, with the A4 tense fix), A9 (minor is correct — not re-graded), A10 (actions-as-tools.mdx is #15942's).

Verification — all readings on `10abca6c28`, merge-base `a5eccf9257`

Derived gates: 102 derived, 102 run, 0 UNRUN — node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran ... reconciles clean at this head. 100 green; 2 NOT MEASURED, both exit 3 (PREREQUISITE NOT MET, which the scripts themselves say is neither a pass nor a finding) and both needing a whole-tree build this container cannot fit in one foreground window: check:dual-build-cjs-loads (no new module and no new import edge hides behind it) and check:type-check-debt (its one moved package, @objectstack/spec, is separately green below, source + scripts + test layers). Both are declared to CI. Four further gates first returned exit 3 or a build-first exit 1 and were re-run to a real green after building the @objectstack/lint, @objectstack/client and @objectstack/client-react closures.
pnpm --filter @objectstack/spec check:generated — all 15 generated artifacts up to date, after gen:migration-registry and then exactly the four --fix proved stale (gen:spec-changes, gen:upgrade-guide, gen:skill-refs, gen:docs) — never the whole set. Every regenerated diff was read: the registry, spec-changes.json and the upgrade guide carry the corrected prose and nothing else.
- One regeneration was a REAL finding, not noise: the A4 rationale was first written as a // block above TOOL_RETIRED_KEY_GUIDANCE, which detached that const's own JSDoc and made the doc generators re-read it as the module summary — rewriting content/docs/references/ai/tool.mdx and skills/objectstack-ai/references/_index.md. The comment now sits INSIDE the object literal beside the key it explains, and both files are untouched in this diff.
pnpm --filter @objectstack/spec test — 484 files / 13142 tests passed (from 483 / 13136: the new pin). pnpm --filter @objectstack/spec typecheck green across tsc --noEmit, check:scripts-typecheck and check:test-typecheck (54 files / 261 errors / 145 pinned signatures held, unchanged — the new file adds none).
Repo-wide lint, not narrowed: eslint . --no-inline-config over 6274 files — 0 errors, 0 warnings, run at this head (6273 before; the delta is the new test file).
check:nul-bytes green; plus an independent control-byte sweep of the 13 changed paths (grep -naP over the control ranges), no hits.
Gates re-run after the final changeset edit and green at this head: the three changeset gates, check:changeset-gate-self-tests, check:objectui-changeset, check:doc-authoring, check:keyed-text-bounds, check:nul-bytes, check:error-code-casing, check:comment-mask-adoption, check:comment-mask-corpus, check:closing-keyword-parity, check:cross-package-test-inputs, check:test-source-alias, check:type-check-coverage, check:dispatcher-error-vocabulary, check:error-code-provenance.
⚠️ One anchoring caveat, recorded rather than hidden: dispatch-gates reports this tree as at least 24 commits behind origin/main, with five family-defining files (two workflows, scripts/nightly-tiers.*, check-skill-line-ratchet.mjs) changed across that range. The derivation is therefore against THIS branch's copies of those files. The change set itself is anchored to the literal merge-base a5eccf9257, never to a moving ref.

Review posture

needs:contract-review stays on this PR and on #16293. The PR stays draft — not flipped ready, not enqueued, no auto-merge — per the reviewing seat's instruction.

Authored by Claude Code in session session_01T6HeZvT9wdSJD1ZxJb5Eno (durable attribution, kept in prose).

…irmation` Declares the request-side member, the refusal code and the refusal detail shape, and rewrites the two passages that described a queue the open framework path does not have. - `AIActionConfirmation` / `AI_ACTION_CONFIRMATION_MEMBER` / `ActionConfirmationRequiredDetails` in `contracts/ai-service.ts`. - `ACTION_CONFIRMATION_REQUIRED` in `ERROR_CODE_LEDGER` under `@objectstack/runtime`, answered 428, registered ahead of its producer. - The refusal is gated on the DECLARED `ai.requiresConfirmation === true`, never on `actionLooksDestructive`'s heuristic fallback. Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno Co-authored-by: Claude <noreply@anthropic.com>

api-surface / export-origins gain exactly the three new contract exports; the ledger's reference page and ApiErrorSchema's code enum gain the one new code; spec-changes.json and the upgrade guide pick up the rewritten ADR-0049 entry prose. No removals in any of them. Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno Co-authored-by: Claude <noreply@anthropic.com>

github-actions · 2026-09-07T07:35:49Z

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 10 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/spec/api-surface/contracts.json, packages/spec/export-origins/contracts.json, packages/spec/spec-changes.json), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

10 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

content/docs/ai/actions-as-tools.mdx (via actionName (symbol, a field of interface ActionConfirmationRequiredDetails), requiresConfirmation (symbol, a field of const object TOOL_RETIRED_KEY_GUIDANCE))
content/docs/ai/tools.mdx (via requiresConfirmation (symbol, a field of const object TOOL_RETIRED_KEY_GUIDANCE))
content/docs/api/client-sdk.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
content/docs/api/error-catalog.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
content/docs/api/error-handling-server.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
content/docs/kernel/contracts/data-engine.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))
content/docs/protocol/objectui/actions.mdx (via requiresConfirmation (symbol, a field of const object TOOL_RETIRED_KEY_GUIDANCE))
content/docs/protocol/objectui/record-alert.mdx (via actionName (symbol, a field of interface ActionConfirmationRequiredDetails))
content/docs/ui/actions.mdx (via actionName (symbol, a field of interface ActionConfirmationRequiredDetails))
content/docs/ui/apps.mdx (via actionName (symbol, a field of interface ActionConfirmationRequiredDetails))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

content/docs/releases/v17.mdx (via ERROR_CODE_LEDGER (symbol, a top-level const object))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

3 changed file(s) yielded no anchor (packages/spec/api-surface/contracts.json, packages/spec/export-origins/contracts.json, packages/spec/spec-changes.json) — pages documenting those are invisible to this run
1 anchor(s) matched too much of the corpus to be a work list: objectName (symbol, 34 pages)
3 name(s) were too generic to anchor anything (single lowercase words)
the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 130 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json ce8caba91403c8f160cb7764c63b08371a13db99 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 7dfa88cca71afdaf94f7243bb4b6bbe2da18e493 — the merge of head 10abca6c2825c3b91e113be6f56ceb3183568adc into base ce8caba91403c8f160cb7764c63b08371a13db99, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 7dfa88cca71afdaf94f7243bb4b6bbe2da18e493 && git checkout 7dfa88cca71afdaf94f7243bb4b6bbe2da18e493
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin ce8caba91403c8f160cb7764c63b08371a13db99 10abca6c2825c3b91e113be6f56ceb3183568adc && git checkout -B drift-repro ce8caba91403c8f160cb7764c63b08371a13db99 && git merge --no-ff 10abca6c2825c3b91e113be6f56ceb3183568adc

node scripts/docs-audit/affected-docs.mjs --json ce8caba91403c8f160cb7764c63b08371a13db99

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs ce8caba91403c8f160cb7764c63b08371a13db99 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

huangyiirene · 2026-09-07T07:57:41Z

Contract review at `CONTRACT_REVIEW_TIER`: PASS — no blocking findings. Ten advisories, and I am holding the PR for a repair pass on six of them.

Reviewed at claude-fable-5-1 by an isolated reviewer, head 09248ca069, base a5eccf9257 (confirmed merge-base). ⚠️ Recorded because it is the right method and I want it copied: the reviewer worked in a detached worktree with no build, so no gate's baseline could move under it — git status --porcelain empty after every gate. That is the clean answer to the regenerate-your-own-baseline confound.

This seat runs claude-opus-5, below tier, and ⛔ did not self-review.

The load-bearing decision is CONFIRMED

Nothing binds the refusal to actionLooksDestructive or to the listing. actionLooksDestructive (:979-982) and the :1014 projection are untouched — the runtime is not in this diff.
The asymmetry holds. Listing true ⇒ either declared-true (refuses; sending the member fixes it) or heuristic-true (no refusal; member accepted and ignored) — a confirming client is correct both ways. Listing false ⇒ the refusal predicate is false in both of its cases. The one residual is by design and is what the ruling chose: a true listing cannot tell a client whether the server would have stopped it.
Measured at head: standardSynonymOf('ACTION_CONFIRMATION_REQUIRED') → undefined with CONFLICT/FORBIDDEN lit as controls; ErrorCode accepts the code and rejects a one-char typo; registered under exactly @objectstack/runtime; five @ts-expect-error legs consumed from a src probe, and ablating one directive yields a real TS2820 — the detector is lit. 4 test files / 77 tests pass.
check:dual-build-cjs-loads (the author's declared NOT MEASURED): nothing load-bearing hides behind it — no new module, no new import edge.

⚠️ Two advisories that are more than cosmetic

A4 — the prose creates an author-facing window the PR's own logic was written to avoid. The rewritten guidance and migration acceptanceCriteria assert present-tense enforcement the runtime does not perform until #15942. Worse, the new acceptance criteria instructs an author to "invoke it WITHOUT the confirmation member and observe the call refused" — before #15942 lands, following that instruction executes the destructive action.

⇒ This is not the dev's error: the card mandated rewriting those passages. It is a real tension between the card's instruction and the card's purpose, and it lands on me. I am taking the reviewer's option (b): make the wording contract-referential until enforcement exists, rather than relying on a release-gating promise.

A2 — the hand-off to #15942 is a live trap. The MCP door strips confirm twice over today (SDK objectFromShape drops unknown keys; the handler forwards only { objectName, recordId, params } at mcp-http-tools.ts:762). ⇒ If #15942's dev enforces only in invokeBusinessAction, every declared-gated action becomes un-invokable via MCP with no way to confirm. Three files in two packages must move together. I am recording that on #15942 now so it cannot be lost.

The repair pass — six advisories, dispatching when a dev slot frees

⛔ The PR stays draft and unarmed until these land. It is priority:p1 + security; "PASS" is not a reason to ship prose that misleads an author about whether a destructive call will be stopped.

A1 — the ledger row cites UNIQUE_SCOPE_CONFIRMATION_REQUIRED as registered "beside the same standard member for the same reason", but that gate answers 409, not 428. 428 itself is defensible and stays; the citation is wrong. One sentence.
A3 — the row is producerless by design (the FLOW_INPUT_SCHEMA_INVALID precedent is real) but cites no issue number, while every sibling row does. Add spec: define the confirmation contract behind action.ai.requiresConfirmation — an unconfirmed run_action on a gated action is refused, and the refusal carries the way to confirm #16293 / MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 / batch Prepare v0.2.0 release for ObjectStack packages #54.
A4 — as above.
A5 — the placement rationale cites "flow call action nodes" as an in-process door; FlowNodeAction has script/subflow/connector_action and no action-call node (control: subflow present). ⭐ And it omits a stronger reason than the one it gives: params is strict by default (enforceActionParams, ADR-0104 D2), so an undeclared confirm inside params would be rejected, not merely collide.
A6 — no pin in the tree for any new symbol (measured: zero hits in test files, same grep lights non-test files). Follow the feat(spec): register FLOW_INPUT_SCHEMA_INVALID — the never-dispatched ADR-0112 code for the definition-level input-schema refusal #12611 shape.
A7 — a second prose site now enumerates mode: 'delete' / variant: 'danger', outside action-requires-confirmation-docblock.pin.test.ts — the pin that exists to stop exactly that rotting.

Accepted as-is

A8 — the extension beyond the card's letter (rewriting acceptanceCriteria) is in-spirit, keep: the ruling removed the queue, so "observe the approval queue hold it" was made false by the ruling itself.
A9 — clause-② minor is correct, matching feat(spec): register FLOW_INPUT_SCHEMA_INVALID — the never-dispatched ADR-0112 code for the definition-level input-schema refusal #12611 and feat(spec): register NAMESPACE_CONFLICT in ERROR_CODE_LEDGER #16252.
A10 — content/docs/ai/actions-as-tools.mdx is accurate today and becomes incomplete once the server refuses ⇒ MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942's job, already on the drift bot's list.

Generated by Claude Code

…/A7) A1: the ledger row cited UNIQUE_SCOPE_CONFIRMATION_REQUIRED as registered beside the same standard member; it answers 409 and so sits beside RESOURCE_CONFLICT. Citation corrected; 428 unchanged. A3: the producerless row now cites #16293, #15942 and decision batch #54. A4: the retirement prescription and the migration entry asserted present-tense enforcement the runtime does not perform yet, and told an author to invoke a destructive action without the confirmation member "and observe the call refused". Both are now contract-referential and warn that such a call RUNS until the door lands. A5: dropped the non-existent flow `call action` node from the placement rationale and added the stronger reason -- `params` is strict by default (enforceActionParams, ADR-0104 D2), so an undeclared `confirm` there is rejected, not merely a collision. The two destination request shapes are now named. A6: added the missing pin -- ErrorCode admission, the ledger row, the standard-synonym reading and a compile witness for confirmationMember. A7: the contract no longer re-lists `mode: 'delete'` / `variant: 'danger'`; it references actionLooksDestructive, leaving one enumeration site under the #13865 pin. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

… A4 tense fix The A4 rationale rides in a comment INSIDE the guidance literal rather than above the const: placed above it, it detached the const's own JSDoc and the doc generators re-read that block as the module summary, rewriting content/docs/references/ai/tool.mdx and skills/objectstack-ai/references/_index.md. Both are untouched again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

The changeset body is the release-time carrier of the same claim the guidance and the migration entry were carrying, so leaving it present-tense would publish exactly the sentence the repair pass removed. It now says the contract is a declaration, that no door performs the refusal yet, and it takes the A5 correction on the `params` placement reason. Grade unchanged: minor, additive. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

huangyiirene · 2026-09-07T09:59:24Z

Delta re-review at `CONTRACT_REVIEW_TIER` (`claude-fable-5-1`) — PASS, no blocking findings

Head 10abca6c28, merge-base a5eccf9257, delta 09248ca069..10abca6c28 (3 commits, 9 files). Method: two detached worktrees at head, --frozen-lockfile --ignore-scripts; one kept pristine for gate readings, one for ablations with a git diff --stat landing proof on every mutation and a revert to porcelain 0 after each.

All six held advisories land correctly. The review did not take the repairs on trust — each was re-measured:

A1 — the false precedent is properly corrected, not merely softened. UNIQUE_SCOPE_CONFIRMATION_REQUIRED was independently confirmed to answer 409 (marketplace-install-local-plugin.ts closes }, 409); its ledger row says 409; errors.zod.ts:178-179 maps 409→RESOURCE_CONFLICT, 428→PRECONDITION_REQUIRED). The row now claims sibling-in-kind only. The 428 justification is byte-unchanged — the correction removed a bad citation without weakening the decision it was wrongly supporting.
A3 — // [#16293] matches the file's own head form, measured across 36 sibling rows; "registered but unemittable" is the ledger header's own term, so split-vs-residue is drawn on the ledger's line rather than the author's.
A4 (SECURITY) — all four sites re-read in full, with the strings joined before grepping because they are 'a ' + 'b ' chains and a line-oriented search would have missed them. Each carries both required clauses: the refusal is declared but not performed, and do not try to verify it by invoking the operation — because before MCP run_action never enforces ai.requiresConfirmation — it is surfaced in list_actions only, while @objectstack/spec guidance tells authors it stops execution #15942 that call RUNS the destructive action. Queue language stays deleted. The tracker-id split was verified as a real constraint, not a story: planting #15942 inside the prescription string reds check:doc-authoring (exit 1, landing proof), green at head.
A5 — FlowNodeAction re-enumerated: no action-call node, with subflow lit as a control. The enforceActionParams asymmetry is confirmed at action-execution.ts:1186 and action-params.zod.ts:45-51.
A6 — the pin is lit for the right reason, and this is the one place the review upgraded its own method. The author's TS2578 argument establishes that the @ts-expect-error directives are consumed, but not why; the reviewer judged that insufficient, took the ablation that does answer it (delete the near-miss directive → TS2322: Type '"confirmed"' is not assignable to type '"confirm"' on that exact line), and it reads right. Three further ablations behave as predicted. check:test-typecheck at 54 / 261 / 145 — the author's numbers exactly.
A7 — de-enumeration confirmed as the right call: a single-token sweep finds the heuristic's legs at exactly one site, the ActionAiSchema.requiresConfirmation docblock still names confirmText as a destructive signal — the #7828 ruling removed that leg #13865-pinned one. A second pinned copy would freeze the list twice.

The generator-detachment claim is verified, and it was worth verifying: content/docs/references/ai/tool.mdx and skills/objectstack-ai/references/_index.md are blob-identical at merge-base and head, no commit touches either, and the JSDoc now sits directly above the const with the rationale inside the literal.

The api-surface leg that was left open is now closed. In a no-build tree it was a prerequisite failure — dist holds no .d.ts — which is not a reading and was correctly refused as one. Taken separately with a 3m11s build from head source: porcelain empty afterwards (so the build's regeneration of authorable-surface/api.json produced no diff, which is the confound that makes this leg go falsely green when done carelessly), then check:api-surface → "public API surface + factory signatures unchanged", exit 0.

Not measured, and declared as such: check:dual-build-cjs-loads and check:type-check-debt — the exit-3 PREREQUISITE NOT MET pair. CI's to answer, and CI has: both green in the run below.

Five advisories, none blocking, none held

Changeset line 10 and the "REAL gate" phrase keep indicative mood but are framed unambiguously by the surrounding sentences; the contract docblock's "a 400" is exact for the REST door while the MCP door returns a tool error; "named once" is true within packages/spec though the #13865 pin header names two prose carriers elsewhere; and the A6 method note above. None is worth another repair round.

CI — read in full this time

37 check runs, all 37 read (the listing pages at 30, and I am not making that mistake twice today): every one success or skipped, Lint & Repo Gates success. 13 files changed, none on the governed surface.

One thing checked because #16554 landed after this branch's base: packages/spec/api-surface/contracts.json is modified here, but ./contracts is not among the ten entry points #16554 rewrote, so there is no regen collision to resolve and the merge=os-regen routing does not come into play. (GitHub runs no custom merge driver, so a collision there would have surfaced as a plain conflict, not a silent resolution.)

Arming. needs:contract-review struck — the review it names has passed.

Generated by Claude Code

…cutionContext` (objectstack-ai#18676) Fixes objectstack-ai#15937 `ToolExecutionContext` in `packages/spec/src/contracts/ai-service.ts` is the contract a tool handler may rely on. A **published handler already authorizes on** `confirmedBlueprintIdentity` — cloud's `apply_blueprint` gate makes a matching blueprint-identity digest one clause of the decision to build a whole app (cloud#1954 / cloud PR objectstack-ai#2005) — while the member it reads was declared only on cloud's own augmented `ToolExecutionContext` and reached by a structural cast. This declares it where the contract lives. Clause-②: yes (widening) — one new OPTIONAL member on a published interface, so the shape a consumer writes against grows. Nothing previously admitted is refused, no member is renamed or retired, and no producer is required to write it. Contract-review tier. The `needs:contract-review` carrier is the seat's on both sides and this PR touches neither. ## The ruling this implements The maintainer's ruling is recorded on objectstack-ai#15937 at comment 5553002827 (2026-09-05), on option 1, verbatim 「同意」. A triage stroke the next morning re-hung `needs-user-decision` on an already-decided card, and the director seat reversed it at 5559258277 with "Nothing to re-decide". So the implementer's brief is the ruling comment, not the card body's two-option analysis. Ruling items 1 and 2 are implemented here. **Item 3 is a read-and-report and is answered below.** **Item 4** — delete cloud's augmentation at `tool-registry.ts:45`, replace the cast in `confirm-gate.ts` with the typed read — is a cloud follow-up card blocked on this field being published and pinned. It is not in this diff, and this seat neither touched cloud nor filed that card. ## What landed **`ToolExecutionContext.confirmedBlueprintIdentity?: string`**, placed next to `userMessageText` because that is the same class of field: route-owner-populated, advisory-to-nobody, never client-derived. Its docblock carries the four things item 1 asks for. - The digest is stamped on a **confirm replay** of an already approved proposal — the consent record saying *this exact blueprint* is the one the user approved. - Populated by whichever layer owns the agent route (cloud, post-cloud ADR-0025), and **only by in-process server code on that route**; never derived from a request body, a tool argument or the transcript. - `undefined` means "no confirmed identity on this turn" and **authorizes nothing** — the same fail-closed reading `actor` and `isSystem` already carry (objectstack-ai#2991). - The consumer is cited by name: cloud#1954 / cloud PR objectstack-ai#2005. **`confirmed-blueprint-identity-contract.pin.test.ts`** — a new pin, following the file's existing `action-confirmation-contract.pin.test.ts` convention. `ToolExecutionContext` had **no test naming it anywhere in this repository** before this PR (`git grep -l ToolExecutionContext` over the tree lit 8 files: two CHANGELOGs, two generated artefacts, one consumer, the contract itself — and zero test files). Six legs, each negative one paired with a lit positive one on the same helper: | leg | what it pins | what makes it able to fail | |---|---|---| | declared on `ToolExecutionContext` | the member, and the digest round-trips | removing the member makes the literal an excess property | | reaches a handler | it travels on `ChatWithToolsOptions.toolExecutionContext` | declaring it on the wrong type compiles nowhere | | optional, absent reads `undefined` | absence is the resting state of a non-replay turn | the lit control reads the same property on a context that carries it | | reads as `string \| undefined` | a handler cannot compile a path that assumes a confirmation | making the member required leaves the directive unused — TS2578 | | typed `string`, not `any` | the member did not arrive untyped | typing it `any`/`unknown` leaves the directive unused — TS2578 | | the spelling is load-bearing | a near-miss is not the confirmation field | renaming the real member reddens the first leg instead | **Changeset**: `@objectstack/spec` **minor**, per ruling item 2. ## Item 3 — `systemInvocation`: read, reported, NOT folded in Measured on this base, repo-wide with same-scope controls: | target | files | reading | |---|---|---| | `systemInvocation` | **0** | the protocol does not declare it either | | lit control `userMessageText` | 1 | the grep reaches, and finds the analogue field | | lit control `isSystem` | 853 | the wide control | | dark control | 0 | — | **Half of the class holds and half is not measurable from here.** The class this card names has two halves: (a) absent from the protocol, and (b) load-bearing for an authorization decision a published handler makes through a structural cast. (a) is confirmed above. (b) lives in `objectstack-ai/cloud`, which is outside this card's scope and which this seat did not open — so it is reported as unmeasured rather than assumed. What the protocol side does say is an asymmetry worth handing to whoever picks this up: **`confirmedBlueprintIdentity` had no protocol counterpart at all**, whereas `systemInvocation` sits beside `isSystem`, which this same interface declares and whose docblock calls it "the ONLY way to obtain system behaviour from the tool loop". So the first question for `systemInvocation` is not "declare it" but "does it duplicate `isSystem`" — and only a "no" makes it this card's case. That is a different first question, so it is **not plainly the same class of omission**, it needs its own card, and this PR does not widen into it. ## Premise re-check on this base The dispatch flagged three premises. All three were re-measured rather than inherited. 1. **The gap is still open.** On base `30be2ac0bb`: `confirmedBlueprintIdentity` across `packages/` = **0 files** (grep exit 1); lit control `userMessageText` = **1 file**; lit control `ToolExecutionContext` = **8 files**; dark control = 0. The one-file control proves the grep reaches `packages/` and finds the analogue field and **nothing more** — the 8-file control is the wide one. 2. **The file moved after the ruling, the interface did not.** `scripts/pm/git-history.mjs touch` answers `fe0d9a4241ab782628e5a7bc4ac61baeb505fbd1`, 2026-09-07T10:00:37Z, +134 lines — two days after the 2026-09-05 ruling, and proved without fetching, the touch and its parent sitting above the shallow floor. Reading that commit's own diff: **not one added or removed line names a `ToolExecutionContext` member**. The +134 is the action-confirmation contract (objectstack-ai#16531) elsewhere in the file. So the interface and `userMessageText`'s docblock were re-read on this base and the docblock matched in shape is the one on the tree; the ruling's quoted field list still describes it, its "UI-context block" being `currentObjectName` / `currentViewName` / `surfaceContext`. 3. **The card's comparison holds.** cloud PR objectstack-ai#2005's body placed `confirmedBlueprintIdentity` "alongside `userMessageText` and `systemInvocation`". Of those three, `userMessageText`'s single repo-wide hit **is** this spec file — the protocol, not an augmentation — while `systemInvocation` has zero. The three were never alike in where they are declared, which is the whole reason this card exists. ## Verification Readings are cited at the commit they were taken on. `pnpm lint` (the repo-wide `eslint . --no-inline-config`) is CI's run; what is below is a declared narrowing with its evidence. - **Build** — `pnpm --filter @objectstack/spec build`, exit 0. `packages/spec/dist/contracts/index.d.ts` carries the member, so the readings below are against a rebuilt tree, not a cached one. `git status` clean after the build: no generator moved a tracked artefact, and `api-surface/contracts.json` is unmoved because it records exported symbol names, not interface members. - **Type-check** — `pnpm --filter @objectstack/spec typecheck`, exit 0 (that is `tsc --noEmit`, `check:scripts-typecheck` and `check:test-typecheck` in series). The test-layer ratchet holds at 54 files / 259 errors / 144 pinned signatures, unchanged. - **Tests** — `pnpm --filter @objectstack/spec test`, exit 0: **486 files, 13856 tests passed**. The new pin, run on its own, is 6 passed. - **Ablation, direction predicted before the run: RED.** From the committed state, the declared member was renamed on disk (delete-anchor 1 to 0, inject-anchor 0 to 1, blob hash moved `bf79a0cc` to `a646979419`), and `check:test-typecheck` went from exit 0 to **exit 1, naming 10 type errors in the new pin file**. The restore leg put HEAD's bytes back — `git hash-object` back to `bf79a0cc3f6fb0505e0edf6c5665c3f004e371f4`, `git diff HEAD` empty, `git status --porcelain` empty — and the same gate returned to exit 0. Both legs ran under a `trap ... EXIT INT TERM` restore with absolute paths. No `dist` preflight: the pin imports `./ai-service` relatively, so it resolves to `src`, and a `dist` reading would be about the wrong artefact. - **Lint, narrowed and declared**, at `5ddd6f45ee`. ① The population comes from eslint's own config: the base block is `files: ['**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}']`, so the changeset `.md` is outside it entirely — eslint says so itself, "File ignored because no matching configuration was supplied". ② `--format json` counts 3 entries, of which 2 are in-population: **0 errors, 0 warnings** on both `.ts` files. ③ Invariance, quoted from `eslint.config.mjs`: "this repo runs one `eslint.config.mjs`, which never enables type-aware linting (no `parserOptions.project`, no typed `@typescript-eslint` rules) for ANY file, test or not." With no type-aware rule, nothing in this diff can move the verdict on a file the diff does not touch; the config's file rosters are likewise untouched. - **Control bytes** — `check:nul-bytes` exit 0 over 8798 files, plus a direct `grep -naP` sweep of the three changed files, which found none. The full re-derived gate sweep, every exit code, and the reconciliation against `dispatch-gates.mjs --ran` are in the `os-dev-report` comment on objectstack-ai#15937. ## Acceptance notes Noted while in the file, **not filed and not fixed here**: - `userMessageText`'s docblock, the line directly above the new member, reads "(cloud, post-ADR-0025)" — a **bare** ADR number for what is, in context, cloud's record. AGENTS.md Prime Directive 13 is explicit: an ADR lives in the repository whose code it governs, cloud decisions are cited "as `cloud ADR-NNNN` — ⛔ never as a bare number, which `scripts/check-adr-anchors.mjs` resolves against *this* registry (the two number independently)". This repository's own `ADR-0025` is `docs/adr/0025-plugin-package-distribution.md`, and every other bare `ADR-0025` in the tree means that one, so a reader following this citation lands on a real page about plugin packaging. The new member spells it `cloud ADR-0025`, which is why the two lines differ. **Not folded in**: it is a different defect class from this card's, so the bounded in-place exemption does not open, and `check:adr-anchors` does not read source docblocks at all (it checks only the entries under `scripts/adr-anchors/`), so nothing is currently red. Reported with dedupe words in the report comment for the triage seat to file or discard. - `ToolExecutionContext` carrying **no test at all** before this PR is now half-closed: the new pin asserts the new member and the thread it travels on, deliberately not the other twelve members. Widening it to the whole interface would be scope this card does not carry. Provenance: authored by an `os-dev` seat under the PM dispatch on objectstack-ai#15937, session `session_01LvwGppdonww4zGLWZo5rho` (https://claude.ai/code/session_01LvwGppdonww4zGLWZo5rho). --- _Generated by [Claude Code](https://claude.ai/code/session_01LvwGppdonww4zGLWZo5rho)_ Co-authored-by: Claude <noreply@anthropic.com>

claude added 2 commits September 7, 2026 06:41

github-actions Bot added size/m documentation Improvements or additions to documentation protocol:ai tooling labels Sep 7, 2026

huangyiirene added the needs:contract-review label Sep 7, 2026 — with Claude

github-actions Bot added the tests label Sep 7, 2026

huangyiirene mentioned this pull request Sep 7, 2026

[finding] spec(liveness): translation.json's WALK BOUNDARY sentence claims "every group is a z.record" — settingsCommon is a plain strictObject #16135

Closed

This was referenced Sep 7, 2026

feat(spec): object-kanban props declare limit, the row cap objectui already implements #16562

Merged

[PM seat] domain:spec — ⏳ vacant #6017

Open

huangyiirene removed the needs:contract-review label Sep 7, 2026 — with Claude

huangyiirene marked this pull request as ready for review September 7, 2026 09:59

huangyiirene added this pull request to the merge queue Sep 7, 2026

os-sales mentioned this pull request Sep 7, 2026

automation resume door: the 400 FLOW_FAILED envelope drops the engine's status: 'stranded' verdict — the wire mirror's member is unreachable on the wire #15221

Closed

Merged via the queue into main with commit fe0d9a4 Sep 7, 2026
42 checks passed

huangyiirene deleted the claude/issue-16293-action-confirmation-contract branch September 7, 2026 10:22

os-sales mentioned this pull request Sep 7, 2026

feat(runtime, spec): the resume door's 400 FLOW_FAILED details carry the engine's stranded verdict #16587

Merged

os-litant mentioned this pull request Sep 17, 2026

spec: declare confirmedBlueprintIdentity on the protocol's ToolExecutionContext #18676

Merged

Navigation Menu

spec: define the confirmation contract behind `action.ai.requiresConfirmation` - #16531

spec: define the confirmation contract behind `action.ai.requiresConfirmation`#16531
huangyiirene merged 5 commits into
mainfrom
claude/issue-16293-action-confirmation-contract

huangyiirene commented Sep 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 7, 2026 •

edited

Loading

Uh oh!

huangyiirene commented Sep 7, 2026

Uh oh!

huangyiirene commented Sep 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

huangyiirene commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The four deliverables

Which predicate gates the refusal, and why

Why 428, and why a ledger code beside PRECONDITION_REQUIRED

Deliberately not done here

The repair pass — the six advisories held from the review

Verification — all readings on 10abca6c28, merge-base a5eccf9257

Review posture

Uh oh!

github-actions Bot commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📓 Docs Drift Check

Uh oh!

huangyiirene commented Sep 7, 2026

Contract review at CONTRACT_REVIEW_TIER: PASS — no blocking findings. Ten advisories, and I am holding the PR for a repair pass on six of them.

The load-bearing decision is CONFIRMED

⚠️ Two advisories that are more than cosmetic

The repair pass — six advisories, dispatching when a dev slot frees

Accepted as-is

Uh oh!

huangyiirene commented Sep 7, 2026

Delta re-review at CONTRACT_REVIEW_TIER (claude-fable-5-1) — PASS, no blocking findings

Five advisories, none blocking, none held

CI — read in full this time

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

huangyiirene commented Sep 7, 2026 •

edited

Loading

Why 428, and why a ledger code beside `PRECONDITION_REQUIRED`

Verification — all readings on `10abca6c28`, merge-base `a5eccf9257`

github-actions Bot commented Sep 7, 2026 •

edited

Loading

Contract review at `CONTRACT_REVIEW_TIER`: PASS — no blocking findings. Ten advisories, and I am holding the PR for a repair pass on six of them.

Delta re-review at `CONTRACT_REVIEW_TIER` (`claude-fable-5-1`) — PASS, no blocking findings